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Distribution of this memo is unlimited. 
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Abstract 


XML-RPC is an Extensible Markup Language-Remote Procedure Calling 
protocol that works over the Internet. It defines an XML format for 
messages that are transfered between clients and servers using HTTP. 
An XML-RPC message encodes either a procedure to be invoked by the 
server, along with the parameters to use in the invocation, or the 
result of an invocation. Procedure parameters and results can be 
scalars, numbers, strings, dates, etc.; they can also be complex 
record and list structures. 


This document specifies a how to use the Blocks Extensible Exchange 
Protocol (BEEP) to transfer messages encoded in the XML-RPC format 
between clients and servers. 
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1. Introduction 


This memo specifies how messages encoded in the XML-RPC [1] format 
are transmitted using a BEEP profile [2]. 


Throughout this memo, the terms "request" and "response" refer to the 
"methodCall" and "methodResponse" elements defined by the XML-RPC 
specification [1]. Further the terms "peer", "client", "server", and 
"one-to-one" are used in the context of BEEP. In particular, 
Sections 2.1 and 2.1.1 of [2] discuss BEEP roles and exchange styles. 


2. BEEP Profile Identification 
The BEEP profile for XML-RPC is identified as 
http://iana.org/beep/transient/xmlrpc 
in the BEEP "profile" element during channel creation. 
In BEEP, when the first channel is successfully created, the 


"serverName" attribute in the "start" element identifies the "virtual 
host" associated with the peer acting in the server role, e.g., 


<start number=’1’ serverName=’ stateserver.example.com’ > 
<profile uri=’http://iana.org/beep/transient/xmlrpc’ /> 
</start> 


The "serverName" attribute is analogous to HTTP’s "Host" request- 
header field (c.f., Section 14.23 of [3]). 
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There are two states in the BEEP profile for XML-RPC, "boot", the 
profile’s initial state, and "ready": 


o In the "boot" state, the peer requesting the creation of the 
channel sends a "bootmsg" (either during channel initialization or 
in a "MSG" message). 


* If the other peer sends a "bootrpy" (either during channel 
initialization or in a "RPY" message), then the "ready" state 
is entered 


* Otherwise, the other peer sends an "error" (either during 
channel initialization or in a "ERR" message), and no state 
change occurs. 


o In the "ready" state, the initiating peer begins an XML-RPC 
message pattern by sending a "MSG" message containing a request. 
The other peer completes the message pattern by sending back a 
"RPY" message containing a response. 


2.1 Profile Initialization 


The boot message is used to identify the resource accessed by the 
channel bound to the BEEP profile for XML-RPC. 


The DTD syntax for the boot message and its response are: 


<!ELEMENT bootmsg EMPTY> 
<!ATTLIST bootmsg 
resource CDATA #REQUIRED> 
<!ELEMENT bootrpy EMPTY> 
The boot message contains a single mandatory attribute: "resource", 


which is analagous to HTTP’s "abs_path" Request-URI parameter (c.f., 
Section 5.1.2 of [3]) 


If the peer acting in the server role recognizes the requested 
resource, it replies with a boot response. Otherwise, if the boot 
message is improperly formed, or if the requested resource isn’t 
recognized, the peer acting in the server role replies with an error 
message (c.f., Section 7.1 of [2]). 


Typically, the boot message and its response are exchanged during 
channel initialization (c.f., Section 2.3.1.2 of [2]). 
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For example, here the boot message and its response are exchanged 
during channel initialization: 


C: <start number=’1’ serverName=’ stateserver.example.com’ > 

C <profile uri='’http://iana.org/beep/transient/xmlrpc’ > 
Cs <![CDATA[<bootmsg resource=’/NumberToName’ />]]> 
Cc </profile> 

C: </start> 

S: <profile uri=’http://iana.org/beep/transient/xmlrpc’ > 

S: <![CDATA[<bootrpy />]]> 

S: </profile> 


The channel bound to the BEEP profile for XML-RPC is now in the 
"ready" state. 


Alternatively, here is an example in which the boot exchange is 


unsuccessful: 
C: <start number=’1’ serverName=’ stateserver.example.com’ > 
C <profile uri='’http://iana.org/beep/transient/xmlrpc’ > 
Cz <![CDATA[<bootmsg resource=’/NameToCapital’ />]]> 
o </profile> 
C: </start> 


S: <profile uri=’http://iana.org/beep/transient/xmlrpc’ > 
S: <! [CDATA[<error code=’ 550'>resource not 

St supported</error>]]> 

S: </profile> 


Although the channel was created successfully, it remains in the 
"boot" state. 


3. XML-RPC Message Packages 


The BEEP profile for XML-RPC transmits requests and responses encoded 
as UTF-8 using the media type "application/xml" [4], e.g., 


MSG 1 1 . 0 364 
Content-Type: application/xml 


<?xml version="1.0"?> 
<methodCall> 
<methodName>examples.getStateName</methodName> 
<params> 
<param> 
<value><i4>41</i4></value> 
</param> 


HHHHHHHHHH 
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Ts </params> 
I: </methodCall> 
I: END 


and its associated response 


RPY 1 1 . 201 100 
Content-Type: application/xml 


<?xml version="1.0"?> 
<methodResponse> 
<params> 
<param> 
<value><string>South Dakota</string></value> 
</param> 
</params> 
</methodRespose> 
END 


PAE ESE cbt EE Se ce eet 


4. XML-RPC Message Exchange 


A request/response exchange involves sending a request, which results 
in a response being returned. 


The BEEP profile for XML-RPC achieves this using a one-to-one 
exchange, in which the client sends a "MSG" message containing an 
request, and the server sends back a "RPY" message containing an 
response. 


The BEEP profile for XML-RPC does not use the "ERR" message for XML- 

RPC faults when performing one-to-one exchanges. Whatever response 

is generated by the server is always returned in the "RPY" message. 
5. URL Schemes 

This memo defines two URL schemes, "xmlrpc.beep" and "xmlrpc.beeps", 

which identify the use of XML-RPC over BEEP over TCP. Note that, at 

present, a "generic" URL scheme for XML-RPC is not defined. 


5.1 The xmlrpc.beep URL Scheme 


The "xmlrpc.beep" URL scheme uses the "generic URI" syntax defined in 
Section 3 of [5], specifically: 


o the value "xmlrpc.beep" is used for the scheme component; and, 


o the server-based naming authority defined in Section 3.2.2 of [5] 
is used for the authority component. 
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o the path component maps to the "resource" component of the boot 
message sent during profile initialization (if absent, it defaults 
to w/") X 


The values of both the scheme and authority components are case- 
insensitive. 


For example, the URL 


xmlrpc.beep://stateserver.example.com/NumberToName 


might result in the example shown in Section 2.1. 
5.1.1 Resolving IP/TCP Address Information 


The "xmlrpc.beep" URL scheme indicates the use of the BEEP profile 
for XML-RPC running over TCP/IP. 


If the authority component contains a domain name and a port number, 
e.g., 


xmlrpc.beep://stateserver.example.com:1026 


then the DNS is queried for the A RRs corresponding to the domain 
name, and the port number is used directly. 


If the authority component contains a domain name and no port number, 
e.g., 


xmlrpc.beep://stateserver.example.com 


the SRV algorithm [6] is used with a service parameter of "xmlrpc- 
beep" and a protocol parameter of "tcp" to determine the IP/TCP 
addressing information. If no appropriate SRV RRs are found (e.g., 
for "_xmlrpc-beep._tcp.stateserver.example.com"), then the DNS is 
queried for the A RRs corresponding to the domain name and the port 
number used is assigned by the IANA for the registration in Section 
6.4. 


If the authority component contains an IP address, e.g., 
xmlrpc.beep://10.0.0.2:1026 


then the DNS is not queried, and the IP address is used directly. If 
a port number is present, it is used directly; otherwise, the port 
number used is assigned by the IANA for the registration in Section 
6.4. 
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While the use of literal IPv6é addresses in URLs is discouraged, if a 
literal IPv6é address is used in a "xmlrpc.beep" URL, it must conform 
to the syntax specified in [7]. 


5.2 The xmlrpc.beeps URL Scheme 


The "xmlrpc.beeps" URL scheme is identical, in all ways, to the 
"xmlrpc.beep" URL scheme specified in Section 5.1, with the exception 
that prior to starting the BEEP profile for XML-RPC, the BEEP session 
must be tuned for privacy. In particular, note that both URL schemes 
use the identical algorithms and parameters for address resolution as 
specified in Section 5.1.1 (e.g., the same service name for SRV 
lookups, the same port number for TCP, and so on). 


There are two ways to perform privacy tuning on a BEEP session, 
either: 


o atransport security profile may be successfully started; or, 


o a user authentication profile that supports transport security may 
be successfully started. 


In either case the client must present the authority component of the 
URL in the "serverName" attribute of the "start" element it uses to 
tune the session for privacy. 


When TLS is used for privacy the client must verify that the 
authority component of the URL matches the server’s identity as 
presented in the server’s certificate. Section 2.4 of [9] describes 
the matching process. 


For the URL: 


xmlrpc.beeps://stateserver.example.com/NumberToName 


the whole process might look like: 


<wait for incoming connection @ stateserver.example.com> 
<open connection to stateserver.example.com> 

RPY 00.0 52 

Content-Type: application/xml 


<greeting /> 

END 

RPY 00 . 0 110 

Content-Type: application/xml 


YANNNAADAAAAAN 


<greeting> 
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<profile uri=’http://iana.org/beep/TLS’ /> 
<profile uri=’http://iana.org/beep/SASL/DIGEST-MD5’ /> 
</greeting> 
END 
MSG 0 1 . 52 158 
Content-Type: application/xml 


<start number='’1' serverName=’ stateserver.example.com’ > 

<profile uri=’http://iana.org/beep/TLS’ > 
<![CDATA[<ready />]]> 

</profile> 

</start> 

END 

RPY 0 1 . 110 121 

Content-Type: application/xml 


<profile uri='’http://iana.org/beep/TLS’ > 
<! [CDATA [<proceed />]]> 

</profile> 

END 


ANNNNNNAADAAAAAAAANHNMNN 


TLS negotiations 


RPY 00 . 0 88 
Content-Type: application/xml 


<greeting> 
<profile uri='’http://iana.org/beep/transient/xmlrpc’ > 
</greeting> 
END 
RPY 00.0 52 
Content-Type: application/xml 


<greeting /> 
END 


AAAAANNNNNNMN 


use the server’s certificate to verify that it is 
in fact stateserver.example.com 


MSG 0 1 . 112 211 
Content-Type: application/xml 


<start number=’ 3’ serverName=’ stateserver.example.com’ > 
<profile uri='’http://iana.org/beep/transient/xmlrpc’ > 
<![CDATA[<bootmsg resource=’ /NumberToName’ />]]> 
</profile> 
</start> 
END 


OOO. OQ. SEA A 
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RPY 0 2 . 341 402 
Content-Type: application/xml 


<profile uri='’http://iana.org/beep/transient/xmlrpc’ > 
<![CDATA[<bootrpy />]]> 

</profile> 

END 


NNnNNnNNNNN 


6. Initial Registrations 
6.1 Registration: The XML-RPC Profile 

Profile Identification: http://iana.org/beep/transient/xmlrpc 
Messages exchanged during Channel Creation: bootmsg, bootrpy 
Messages starting one-to-one exchanges: bootmsg, methodCall 
Messages in positive replies: bootrpy, methodResponse 
Messages in negative replies: error 
Messages in one-to-many exchanges: none 


Message Syntax: methodCall, methodResponse as defined in [1] 


Message Semantics: c.f., [1] 

Contact Information: Ward Harold <wharold@us.ibm.com> 
6.2 Registration: The xmlrpc.beep URL Scheme 

URL scheme name: xmlrpc.beep 

URL scheme syntax: c.f., Section 5.1 


Character encoding considerations: c.f., the "generic URI" syntax 
defined in Section 3 of [5] 


Intended usage: identifies a XML-RPC resource made available using 
the BEEP profile for XML-RPC 


Applications using this scheme: c.f., "Intended usage", above 
Interoperability considerations: n/a 


Security Considerations: c.f., Section 7 
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Relevant Publications: c.f., [1], and [2] 
Contact Information: Ward Harold <wharold@us.ibm.com> 
Author/Change controller: the IESG 
6.3 Registration: The xmlrpc.beeps URL Scheme 
URL scheme name: xmlrpc.beeps 
URL scheme syntax: c.f. 


, section 5.2 


Character encoding considerations: c.f., the "generic URI" syntax 
defined in Section 3 of [5] 


Intended usage: identifies a XML-RPC resource made available using 
the BEEP profile for XML-RPC after the BEEP session has been tuned 
for privacy 


Applications using this scheme: c.f., "Intended usage", above 
Interoperability considerations: n/a 

Security Considerations: c.f., Section 7 

Relevant Publications: c.f., [1], and [2] 

Contact Information: Ward Harold <wharold@us.ibm.com> 


Author/Change controller: the IESG 


6.4 Registration: The System (Well-Known) TCP port number for XML-RPC 
over BEEP 


Protocol Number: TCP 


Message Formats, Types, Opcodes, and Sequences: c.f., Section 2.1 


Functions: c.f., [1] 

Use of Broadcast/Multicast: none 
Proposed Name: XML-RPC over BEEP 
Short name: xmlrpc—beep 


Contact Information: Ward Harold <wharold@us.ibm.com> 
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7. Security Considerations 


Although service provisioning is a policy matter, at a minimum, all 
implementations must provide the following tuning profiles: 


for authentication: http://iana.org/beep/SASL/DIGEST-MD5 


for confidentiality: http://iana.org/beep/TLS (using the 
TLS_RSA_WITH_3DES_EDE_CBC_SHA cipher) 


for both: http://iana.org/beep/TLS (using the 
TLS_RSA_WITH_3DES_EDE_CBC_SHA cipher supporting client-side 
certificates) 


Further, implementations may choose to offer MIME-based security 
services providing message integrity and confidentiality, such as 
OpenPGP [8] or S/MIME [10]. 


Regardless, consult [2]’s Section 9 for a discussion of BEEP-specific 
security issues. 
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Appendix A. Acknowledgements 


This document is based, in part, on Using SOAP in BEEP [11] and the 
author gratefully acknowledges the contributions of Marshall Rose 


Appendix B. IANA Considerations 


The IANA has registered the profile specified in Section 6.1, and has 
selected an IANA-specific URI, e.g., 


http://iana.org/beep/xmlrpc 


The IANA has registered "xmlrpc.beep" and "xmlrpc.beeps" as URL 
schemes, as specified in Section 6.2 and Section 6.3, respectively. 
(See: http://www.iana.org/assignments/uri-schemes) 


The IANA has registered "XML-RPC over BEEP" as a TCP port number 
(602), as specified in Section 6.4. (See: 
http://www.iana.org/assignments/port-numbers) 
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Full Copyright Statement 
Copyright (C) The Internet Society (2003). All Rights Reserved. 


This document and translations of it may be copied and furnished to 
others, and derivative works that comment on or otherwise explain it 
or assist in its implementation may be prepared, copied, published 
and distributed, in whole or in part, without restriction of any 
kind, provided that the above copyright notice and this paragraph are 
included on all such copies and derivative works. However, this 
document itself may not be modified in any way, such as by removing 
the copyright notice or references to the Internet Society or other 
Internet organizations, except as needed for the purpose of 
developing Internet standards in which case the procedures for 
copyrights defined in the Internet Standards process must be 
followed, or as required to translate it into languages other than 
English. 


The limited permissions granted above are perpetual and will not be 
revoked by the Internet Society or its successors or assignees. 


This document and the information contained herein is provided on an 
"AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING 
TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING 
BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION 
HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF 
MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. 
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